home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section3 / bcp_colfmt.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  6.7 KB  |  174 lines
  1. .Na "bcp_colfmt"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Specify the format of a host file for bulk copy purposes.
  6. .Ih "bcp, specify the host file format"
  7. .Sy
  8. .Sf "RETCODE bcp_colfmt (dbproc, host_colnum, host_type,"
  9. .sp -1v
  10. .Sf "                    host_prefixlen, host_collen, host_term,"
  11. .sp -1v
  12. .Sf "                    host_termlen, table_colnum)"
  13. .Sp "DBPROCESS" "*dbproc"
  14. .Sp "int" "host_colnum"
  15. .Sp "int" "host_type"
  16. .Sp "int" "host_prefixlen"
  17. .Sp "DBINT" "host_collen"
  18. .Sp "BYTE" "*host_term"
  19. .Sp "int" "host_termlen"
  20. .Sp "int" "table_colnum"
  21. .Co
  22. .Bl
  23. \f2bcp_colfmt()\f1 allows you to specify the host file format for bulk copies.
  24. For bulk copy purposes, a format contains the following parts:
  25. .in +5n
  26. .Bl *
  27. A mapping from host file columns to database columns.
  28. .Bl *
  29. The datatype of each host file column.
  30. .Bl *
  31. The length of the optional length prefix of each column.
  32. .Bl *
  33. The maximum length of the host file column's data.
  34. .Bl *
  35. The optional terminating byte sequence for each column.
  36. .Bl *
  37. The length of this optional terminating byte sequence.
  38. .in -5n
  39. .Bl
  40. Each call to \f2bcp_colfmt()\f1 specifies the format for one host file
  41. column. For example, if you have a table with five columns, and want to
  42. change the default settings for three of those columns, you should
  43. first call \f2bcp_columns(dbproc, 5)\f1, and then call \f2bcp_colfmt()\f1 five times,
  44. with three of those calls setting your custom format.
  45. The remaining two calls should have their \f2host_type\f1 set to 0, and their 
  46. \f2host_prefixlen\f1, \f2host_collen\f1, and \f2host_termlen\f1 parameters set to -1. 
  47. The result of this would be to copy all five columns\(emthree with your
  48. customized format and two with the default format.
  49. .Bl
  50. \f2bcp_columns()\f1 \f2must\f1 be called before any calls to \f2bcp_colfmt()\f1.
  51. .Bl
  52. You \f2must\f1 call \f2bcp_colfmt()\f1 for every column in the host file,
  53. regardless of whether some of those columns use the default format
  54. or are skipped.
  55. .Bl
  56. To skip a column, set the \f2table_column\f1 parameter to 0.
  57. .Bl
  58. For information on the \f2bcp\f1 utility program, see its manual page
  59. in the \f2Commands Reference\f1.
  60. .Bz
  61. .Pa
  62. .Pi dbproc
  63. A pointer to the DBPROCESS structure that provides the connection
  64. for a particular front-end/\*S process.  It contains all the
  65. information that \*L uses to manage communications and data between the
  66. front end and \*S.
  67. .Pi host_colnum
  68. The column in the host file whose format is being specified.
  69. The first column is number 1.
  70. .Pi host_type
  71. The datatype of this column in the host file, expressed as a \*S datatype. 
  72. If it is different from the datatype of the corresponding column
  73. in the database table (\f2table_colnum\f1), the conversion will
  74. be performed automatically. 
  75. See the \f2dbconvert()\f1 manual page
  76. for a table of allowable data conversions.
  77. That manual page also contains a list of \*S datatypes.
  78. .sp 0.5v
  79. If you want to specify the same datatype as in the corresponding
  80. column of the database table (\f2table_colnum\f1), this parameter
  81. should be set to 0.
  82. .Pi host_prefixlen
  83. The length of the length prefix for this column in the
  84. host file. 
  85. Legal prefix lengths are
  86. 1, 2, and 4 bytes. To avoid using a length prefix, this
  87. parameter should be set to 0. To let \f2bcp\f1 decide whether 
  88. to use a length prefix,
  89. this parameter should be set to -1.
  90. In such a case, \f2bcp\f1 will use a length prefix (of whatever length is necessary)
  91. if the database column length is variable.
  92. .sp 0.5v
  93. If more than one means of specifying a host file column length
  94. is used (such as a length prefix and a maximum column length,
  95. or a length prefix and a terminator sequence), \f2bcp\f1 will look at
  96. all of them and use the one that results in the shortest amount
  97. of data being copied.
  98. .sp 0.5v
  99. One valuable use for length prefixes is to simplify the specifying
  100. of null data values in a host file. 
  101. For instance, assume you have a 1-byte length prefix for a 4-byte integer column.
  102. Ordinarily, the length prefix will contain a value of 4, to indicate that
  103. a 4-byte value follows.
  104. However, if the value of the column is null, the length prefix can be set to 0,
  105. to indicate that 0 bytes follow for the column.
  106. .Pi host_collen
  107. The maximum length of this column's data in the host file,
  108. \f2not\f1 including the length of any length prefix and/or terminator. 
  109. Setting \f2host_collen\f1 to 0 signifies that the data is null.
  110. Setting \f2host_collen\f1 to -1 indicates that the system should ignore
  111. this parameter (\f2i.e.,\f1 there is no default maximum length).
  112. .sp 0.5v
  113. For fixed-length datatypes, such as integers,
  114. the length of the data is constant, except for the special case of null values.
  115. Therefore, for fixed-length datatypes, \f2host_collen\f1 must always
  116. be -1, except when the data is null, in which case \f2host_collen\f1
  117. must be 0.
  118. .sp 0.5v
  119. For character, text, binary, and image data, \f2host_collen\f1 can be
  120. -1, 0, or some positive value.
  121. If \f2host_collen\f1 is -1, the system will use either a length prefix
  122. or a terminator sequence to determine the length of the data.
  123. (If both are supplied, the system will use the one that results in 
  124. the shortest amount of data being copied.)
  125. If \f2host_collen\f1 is -1 and neither a prefix length nor a 
  126. terminator sequence is specified, the system will return an error message.
  127. If \f2host_collen\f1 is 0, the system assumes the data is null.
  128. If \f2host_collen\f1 is some positive value, the system uses \f2host_collen\f1 as
  129. the maximum data length.
  130. However, if, in addition to a positive \f2host_collen\f1,
  131. a prefix length and/or terminator sequence is provided,
  132. the system determines the data length by using the method 
  133. that results in the shortest amount of data being copied.
  134. .Pi host_term
  135. The terminator sequence to be used for this column. 
  136. This parameter is mainly useful for character, text, binary, and image data
  137. types, because all other types are of fixed length. 
  138. To avoid using a terminator, set this parameter to NULL.
  139. To set the terminator to the NULL character, set \f2host_term\f1 to "\\0".
  140. To make the tab character the terminator, set \f2host_term\f1 to
  141. "\\t".
  142. To make the newline character the terminator, set
  143. \f2host_term\f1 to "\\n".
  144. .sp 0.5v
  145. If more than one means of specifying a host file column length
  146. is used (such as a terminator and a length prefix,
  147. or a terminator and a maximum column length), \f2bcp\f1 will
  148. look at all of them and use the one that results in the shortest amount
  149. of data being copied.
  150. .Pi host_termlen
  151. The length, in bytes, of the terminator sequence to be used
  152. for this column. To avoid using a terminator, set this value
  153. to -1.
  154. .Pi table_colnum
  155. The corresponding column in the database table. If this
  156. value is 0, this column will \f2not\f1 be copied. The
  157. first column is column 1.
  158. .in -.375i
  159. .Re
  160. .br
  161. SUCCEED or FAIL.
  162. .Sa
  163. bcp_batch,
  164. bcp_bind,
  165. bcp_collen,
  166. bcp_colptr,
  167. bcp_columns,
  168. bcp_control,
  169. bcp_done,
  170. bcp_exec,
  171. bcp_init,
  172. bcp_sendrow
  173. .mc
  174.